[Amazon Connect] GetMetricDataで準リアルタイムな履歴メトリックスを取得する

SIN

2019.06.16

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

1 はじめに

AIソリューション部の平内（SIN）です。

Amazon Connect(以下、Comnnect)ではｎ、昨年9月以降、キューメトリクスAPIが利用可能になっています。

APIとしては、リアルタイムメトリクスにアクセスできるGetCurrentMetricDataと、直前24時間からの準リアルタイムの履歴メトリクスにアクセスできるGetMetricDataの2つがあります。

今回は、このうち、準リアルタイムの履歴メトリクスが取得できる、GetMetricDataについて確認してみました。

参考：GetMetricData

参考：GetCurrentMetricData

2 制約等

(1) 利用制限

GetMetricDataは、1秒間に5コールまでという制限があり、これを超える場合は上限緩和の処置が必要です。

参考：Class: AWS.Connect

(2) 取得範囲

開始時間と終了時刻の間隔は、24時間以内である必要があります。この指定を超える場合、InvalidParameterExceptionのエラーとなります。

(3) 時間指定

開始時間と終了時刻は、10：05、10：10、10：15のような5分の倍数である必要があります。

(4) パーミッション

GetMetricDataを使用するためには、以下のパーミッションが必要です。

connect:GetMetricData

(5) データ反映

これは、個人的な使用感になってしまいますが、直近の時間を指定すると、データが反映されていない事があります。履歴メトリックスのスケジュール保存でも、指定した時間から15分遅れて処理されることから、それぐらいのマージンが必須なのかも知れません。

3 SDK

JavaScriptのSDKから利用する場合は、以下のようになります。

var connect = new AWS.Connect();
connect.createUser(params, function (err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});

パラメータの形式は、次のとおりです。

参考：Class: AWS.Connect

var params = {
EndTime: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789, /* required */
Filters: { /* required */
Channels: [
VOICE,
/* more items */
],
Queues: [
'STRING_VALUE',
/* more items */
]
},
HistoricalMetrics: [ /* required */
{
Name: CONTACTS_QUEUED | CONTACTS_HANDLED | CONTACTS_ABANDONED | CONTACTS_CONSULTED | CONTACTS_AGENT_HUNG_UP_FIRST | CONTACTS_HANDLED_INCOMING | CONTACTS_HANDLED_OUTBOUND | CONTACTS_HOLD_ABANDONS | CONTACTS_TRANSFERRED_IN | CONTACTS_TRANSFERRED_OUT | CONTACTS_TRANSFERRED_IN_FROM_QUEUE | CONTACTS_TRANSFERRED_OUT_FROM_QUEUE | CONTACTS_MISSED | CALLBACK_CONTACTS_HANDLED | API_CONTACTS_HANDLED | OCCUPANCY | HANDLE_TIME | AFTER_CONTACT_WORK_TIME | QUEUED_TIME | ABANDON_TIME | QUEUE_ANSWER_TIME | HOLD_TIME | INTERACTION_TIME | INTERACTION_AND_HOLD_TIME | SERVICE_LEVEL,
Statistic: SUM | MAX | AVG,
Threshold: {
Comparison: LT,
ThresholdValue: 'NUMBER_VALUE'
},
Unit: SECONDS | COUNT | PERCENT
},
/* more items */
],
InstanceId: 'STRING_VALUE', /* required */
StartTime: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789, /* required */
Groupings: [
QUEUE | CHANNEL,
/* more items */
],
MaxResults: 'NUMBER_VALUE',
NextToken: 'STRING_VALUE'
};
connect.getMetricData(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});

4 HistoricalMetric

パラメータ HistoricalMetricには、取得したい、メトリックスを配列で渡すことになりますが、指定可能な名前はは、以下のとおりです。

参考：HistoricalMetric

Valid Values: CONTACTS_QUEUED | CONTACTS_HANDLED | CONTACTS_ABANDONED |
CONTACTS_CONSULTED | CONTACTS_AGENT_HUNG_UP_FIRST | CONTACTS_HANDLED_INCOMING |
CONTACTS_HANDLED_OUTBOUND | CONTACTS_HOLD_ABANDONS | CONTACTS_TRANSFERRED_IN |
CONTACTS_TRANSFERRED_OUT | CONTACTS_TRANSFERRED_IN_FROM_QUEUE |
CONTACTS_TRANSFERRED_OUT_FROM_QUEUE | CONTACTS_MISSED | CALLBACK_CONTACTS_HANDLED |
API_CONTACTS_HANDLED | OCCUPANCY | HANDLE_TIME | AFTER_CONTACT_WORK_TIME |
QUEUED_TIME | ABANDON_TIME | QUEUE_ANSWER_TIME | HOLD_TIME | INTERACTION_TIME |
INTERACTION_AND_HOLD_TIME | SERVICE_LEVEL

ここで、コンソールの履歴メトリックスから指定可能な項目と比較してみると、以下のようになります。

よく見てみると、コンソールからの方が、全然多いことに気が付きます。特に、AVGのみで、SUMが存在しない項目が多数あるので、総数となるメトリックスと取得時間とで計算が必要そうです。

例えば、キューに関するメトリックスであれば、総数である、CONTACT_HANDLEと、取得時間から計算するイメージです。

5 コード

最後に、データ取得の一例です。2019.5.30の13:00(JST)から、2019.5.30の15:00(JST)までの3時間を取得しています。

const AWS = require("aws-sdk");
const connect = new AWS.Connect();

const historicalMetrics = [
{Name: "ABANDON_TIME",Unit: "SECONDS",Statistic: "AVG"},
{Name: "AFTER_CONTACT_WORK_TIME",Unit: "SECONDS",Statistic: "AVG"},
{Name: "API_CONTACTS_HANDLED",Unit: "COUNT",Statistic: "SUM"},
{Name: "CALLBACK_CONTACTS_HANDLED",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_ABANDONED",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_AGENT_HUNG_UP_FIRST",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_CONSULTED",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_HANDLED",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_HANDLED_INCOMING",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_HANDLED_OUTBOUND",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_HOLD_ABANDONS",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_MISSED",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_QUEUED",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_TRANSFERRED_IN",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_TRANSFERRED_IN_FROM_QUEUE",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_TRANSFERRED_OUT",Unit: "COUNT",Statistic: "SUM"},
{Name: "CONTACTS_TRANSFERRED_OUT_FROM_QUEUE",Unit: "COUNT",Statistic: "SUM"},
{Name: "HANDLE_TIME",Unit: "SECONDS",Statistic: "AVG"},
{Name: "HOLD_TIME",Unit: "SECONDS",Statistic: "AVG"},
{Name: "INTERACTION_AND_HOLD_TIME",Unit: "SECONDS",Statistic: "AVG"},
{Name: "INTERACTION_TIME",Unit: "SECONDS",Statistic: "AVG"},
{Name: "OCCUPANCY",Unit: "PERCENT",Statistic: "AVG"},
{Name: "QUEUE_ANSWER_TIME",Unit: "SECONDS",Statistic: "AVG"},
{Name: "QUEUED_TIME",Unit: "SECONDS",Statistic: "MAX"},
{Name: "SERVICE_LEVEL",Unit: "PERCENT",Statistic: "AVG", Threshold: { Comparison: "LT",ThresholdValue: 60}},
];

async function job(){
const endTime = new Date(2019, 5 - 1, 30, 15, 0, 0);
const startTime = new Date(2019, 5 - 1, 30, 13, 0, 0);

const queueId = '249f1a68-ffd4-47fc-89a2-dbe00bf1c4dd'
const instanceId = '9a112eb9-b037-43d3-8113-53f615b8406f';

var params = {
EndTime: endTime,
Filters: {
Queues: [
queueId
]
},
HistoricalMetrics: historicalMetrics,
InstanceId: instanceId,
StartTime: startTime,
Groupings: [
"QUEUE"
],
};
const data = await connect.getMetricData(params).promise();
const metricResult = data.MetricResults[0];

let results = [];
metricResult.Collections.forEach( collection => {
var name = collection.Metric.Name;
var value = collection.Value;
results.push(name + ":" + value + ":" + tags[name]);
})
results = results.sort().forEach( result =>{
console.log(result);
})
}

job();

const tags = {
"ABANDON_TIME":"平均キュー中止時間(コールを中止する前にお客様がキューで経過した平均時間)",
"CONTACTS_MISSED":"問い合わせの不在着信(エージェントにルーティングされたけれども、通話を承認しなかった場合にカウントされる)",
"OCCUPANCY":"利用率",
"CONTACTS_ABANDONED":"中止された問い合わせ(キューで待機中にエージェントに接続する前にお客様が切断した問い合わせの数)",
"CONTACTS_QUEUED":"キューに保存された問い合わせ",
"QUEUED_TIME":"キューに入っている最大時間",
"SERVICE_LEVEL":"SLA",
"AFTER_CONTACT_WORK_TIME":"連絡作業後の平均時間",
"CONTACTS_HANDLED":"対応した問い合わせ",
"CONTACTS_HANDLED_INCOMING":"対応した着信問い合わせ",
"HANDLE_TIME":"平均処理時間",
"QUEUE_ANSWER_TIME":"平均キュー応答時間",
"INTERACTION_AND_HOLD_TIME":"エージェントの対応時間とお客様の保留時間の平均",
"INTERACTION_TIME":"エージェントの平均対応時間",
"CONTACTS_AGENT_HUNG_UP_FIRST":"エージェントが先に切断した問い合わせ",
"CONTACTS_HOLD_ABANDONS":"保留中に切断された問い合わせ(エージェント＋顧客)",
"CONTACTS_HANDLED_OUTBOUND":"対応した発信問い合わせ"
}